home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kcommand.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  8.7 KB  |  290 lines
  1. /* This file is part of the KDE project
  2.    Copyright (C) 2000 Werner Trobin <trobin@kde.org>
  3.    Copyright (C) 2000 David Faure <faure@kde.org>
  4.  
  5.    This library is free software; you can redistribute it and/or
  6.    modify it under the terms of the GNU Library General Public
  7.    License as published by the Free Software Foundation; either
  8.    version 2 of the License, or (at your option) any later version.
  9.  
  10.    This library is distributed in the hope that it will be useful,
  11.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.    Library General Public License for more details.
  14.  
  15.    You should have received a copy of the GNU Library General Public License
  16.    along with this library; see the file COPYING.LIB.  If not, write to
  17.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.    Boston, MA 02110-1301, USA.
  19. */
  20.  
  21. #ifndef kcommand_h
  22. #define kcommand_h
  23.  
  24. #include <qptrlist.h>
  25. #include <qstring.h>
  26. #include <qobject.h>
  27. #include <kdelibs_export.h>
  28.  
  29. class KAction;
  30. class KActionCollection;
  31. class QPopupMenu;
  32.  
  33. /**
  34.  * The abstract base class for all Commands. Commands are used to
  35.  * store information needed for Undo/Redo functionality...
  36.  */
  37. class KDEUI_EXPORT KCommand
  38. {
  39. protected:
  40.     /**
  41.      * Creates a command.
  42.      */
  43.     KCommand() {}
  44.  
  45. public:
  46.     virtual ~KCommand();
  47.  
  48.     /**
  49.      * The main method: executes this command.
  50.      * Implement here what this command is about, and remember to
  51.      * record any information that will be helpful for #unexecute.
  52.      */
  53.     virtual void execute() = 0;
  54.     /**
  55.      * Unexecutes (undo) this command.
  56.      * Implement here the steps to take for undoing the command.
  57.      * If your application uses actions for everything (it should),
  58.      * and if you implement unexecute correctly, the application is in the same
  59.      * state after unexecute as it was before execute. This means, the next
  60.      * call to execute will do the same thing as it did the first time.
  61.      */
  62.     virtual void unexecute() = 0;
  63.  
  64.     /**
  65.      * @return the name of this command, translated, since it will appear
  66.      * in the menus.
  67.      */
  68.     virtual QString name() const = 0;
  69. protected:
  70.     virtual void virtual_hook( int id, void* data );
  71. };
  72.  
  73. /**
  74.  * A command which stores its name.
  75.  * It is more memory-efficient to use KCommand and to implement the name() method,
  76.  * but in some cases it's more simple or more flexible to store the name at creation time.
  77.  */
  78. class KDEUI_EXPORT KNamedCommand : public KCommand
  79. {
  80. protected:
  81.     /**
  82.      * Creates a command.
  83.      * @param name the name of this command, translated, since it will appear
  84.      * in the menus.
  85.      */
  86.     KNamedCommand(const QString &name) : KCommand(), m_name(name) {}
  87.  
  88. public:
  89.     /**
  90.      * @return the name of this command
  91.      */
  92.     virtual QString name() const { return m_name; }
  93.     /**
  94.      * Updates the name of this command.
  95.      * Rarely necessary.
  96.      */
  97.     void setName(const QString &name) { m_name=name; }
  98.  
  99. private:
  100.     QString m_name;
  101. protected:
  102.     virtual void virtual_hook( int id, void* data );
  103. };
  104.  
  105. /**
  106.  * A Macro Command is a command that holds several sub-commands.
  107.  * It will appear as one to the user and in the command history,
  108.  * but it can use the implementation of multiple commands internally.
  109.  */
  110. class KDEUI_EXPORT KMacroCommand : public KNamedCommand
  111. {
  112. public:
  113.     /**
  114.      * Creates a macro command. You will then need to call addCommand
  115.      * for each subcommand to be added to this macro command.
  116.      * @param name the name of this command, translated, since it will appear
  117.      * in the menus.
  118.      */
  119.     KMacroCommand( const QString & name );
  120.     virtual ~KMacroCommand() {}
  121.  
  122.     /**
  123.      * Appends a command to this macro command.
  124.      * The ownership is transfered to the macro command.
  125.      */
  126.     void addCommand(KCommand *command);
  127.  
  128.     /**
  129.      * Executes this command, i.e. execute all the sub-commands
  130.      * in the order in which they were added.
  131.      */
  132.     virtual void execute();
  133.     /**
  134.      * Undoes the execution of this command, i.e. #unexecute all the sub-commands
  135.      * in the _reverse_ order to the one in which they were added.
  136.      */
  137.     virtual void unexecute();
  138.  
  139. protected:
  140.     QPtrList<KCommand> m_commands;
  141. protected:
  142.     virtual void virtual_hook( int id, void* data );
  143. };
  144.  
  145.  
  146. /**
  147.  * The command history stores a (user) configurable amount of
  148.  * Commands. It keeps track of its size and deletes commands
  149.  * if it gets too large. The user can set a maximum undo and
  150.  * a maximum redo limit (e.g. max. 50 undo / 30 redo commands).
  151.  * The KCommandHistory keeps track of the "borders" and deletes
  152.  * commands, if appropriate. It also activates/deactivates the
  153.  * undo/redo actions in the menu and changes the text according
  154.  * to the name of the command.
  155.  */
  156. class KDEUI_EXPORT KCommandHistory : public QObject {
  157.     Q_OBJECT
  158. public:
  159.     /**
  160.      * Creates a command history, to store commands.
  161.      * This constructor doesn't create actions, so you need to call
  162.      * #undo and #redo yourself.
  163.      */
  164.     KCommandHistory();
  165.  
  166.     /**
  167.      * Creates a command history, to store commands.
  168.      * This also creates an undo and a redo action, in the @p actionCollection,
  169.      * using the standard names ("edit_undo" and "edit_redo").
  170.      * @param withMenus if true, the actions will display a menu when plugged
  171.      * into a toolbar.
  172.      * @param actionCollection the parent collection
  173.      */
  174.     KCommandHistory(KActionCollection *actionCollection, bool withMenus = true);
  175.  
  176.     /**
  177.      * Destructs the command history object.
  178.      */
  179.     virtual ~KCommandHistory();
  180.  
  181.     /**
  182.      * Erases all the undo/redo history.
  183.      * Use this when reloading the data, for instance, since this invalidates
  184.      * all the commands.
  185.      */
  186.     void clear();
  187.  
  188.     /**
  189.      * Adds a command to the history. Call this for each @p command you create.
  190.      * Unless you set @p execute to false, this will also execute the command.
  191.      * This means, most of the application's code will look like
  192.      *    MyCommand * cmd = new MyCommand(i18n("Capitalized Name"), parameters);
  193.      *    m_historyCommand.addCommand( cmd );
  194.      */
  195.     void addCommand(KCommand *command, bool execute=true);
  196.  
  197.     /**
  198.      * @return the maximum number of items in the undo history
  199.      */
  200.     int undoLimit() const { return m_undoLimit; }
  201.     /**
  202.      * Sets the maximum number of items in the undo history.
  203.      */
  204.     void setUndoLimit(int limit);
  205.     /**
  206.      * @return the maximum number of items in the redo history
  207.      */
  208.     int redoLimit() const { return m_redoLimit; }
  209.     /**
  210.      * Sets the maximum number of items in the redo history.
  211.      */
  212.     void setRedoLimit(int limit);
  213.  
  214.     /**
  215.      * Enable or disable the undo and redo actions.
  216.      * This isn't usually necessary, but this method can be useful if
  217.      * you disable all actions (to go to a "readonly" state), and then
  218.      * want to come back to a readwrite mode.
  219.      */
  220.     void updateActions();
  221.  
  222. public slots:
  223.     /**
  224.      * Undoes the last action.
  225.      * Call this if you don't use the builtin KActions.
  226.      */
  227.     virtual void undo();
  228.     /**
  229.      * Redoes the last undone action.
  230.      * Call this if you don't use the builtin KActions.
  231.      */
  232.     virtual void redo();
  233.     /**
  234.      * Remembers when you saved the document.
  235.      * Call this right after saving the document. As soon as
  236.      * the history reaches the current index again (via some
  237.      * undo/redo operations) it will emit documentRestored
  238.      * If you implemented undo/redo properly the document is
  239.      * the same you saved before.
  240.      */
  241.     virtual void documentSaved();
  242.  
  243. protected slots:
  244.     void slotUndoAboutToShow();
  245.     void slotUndoActivated( int );
  246.     void slotRedoAboutToShow();
  247.     void slotRedoActivated( int );
  248.  
  249. signals:
  250.     /**
  251.      * Emitted every time a command is executed
  252.      * (whether by addCommand, undo or redo).
  253.      * You can use this to update the GUI, for instance.
  254.      *
  255.      * KDE4 TODO: remove
  256.      */
  257.     void commandExecuted();
  258.  
  259.     /**
  260.      * Emitted every time a command is executed
  261.      * (whether by addCommand, undo or redo).
  262.      * You can use this to update the GUI, for instance.
  263.      * @param command was executed
  264.      * @since 3.5
  265.      */
  266.     void commandExecuted(KCommand *command);
  267.  
  268.     /**
  269.      * Emitted every time we reach the index where you
  270.      * saved the document for the last time. See documentSaved
  271.      */
  272.     void documentRestored();
  273.  
  274. private:
  275.     void clipCommands();  // ensures that the limits are kept
  276.  
  277.     QPtrList<KCommand> m_commands;
  278.     KAction *m_undo, *m_redo;
  279.     QPopupMenu *m_undoPopup, *m_redoPopup;
  280.     int m_undoLimit, m_redoLimit;
  281.     bool m_first;  // attention: it's the first command in the list!
  282. protected:
  283.     virtual void virtual_hook( int id, void* data );
  284. private:
  285.     class KCommandHistoryPrivate;
  286.     KCommandHistoryPrivate *d;
  287. };
  288.  
  289. #endif
  290.